/**
 * @file parameter_data.h
 * @brief 参数读写数据模块 - 处理参数读写相关的所有数据类型
 * @details 本文件定义了104协议的参数读写数据处理功能，包括参数特征标识、
 *          TLV数据、参数读写命令等数据类型的结构定义和函数声明。
 *          支持完整的数据转换和验证功能。
 * 
 * @author zyb
 * @date 2025-10-18
 * @version 1.0
 * 
 * @note 所有函数都遵循104协议规范，确保严格的数据处理
 * @warning 数据转换失败时应返回相应的错误码，便于上层处理
 * 
 * @see parameter_data.c
 * @see protocol_types.h
 * @see buffer_utils.h
 * @see time_utils.h
 */

#ifndef PARAMETER_DATA_H
#define PARAMETER_DATA_H

#include "../../common/types/include/protocol_types.h"

#ifdef __cplusplus
extern "C" {
#endif

/* ==================== 参数读写数据类型定义 ==================== */

/**
 * @brief 参数特征标识 (Parameter Identification)
 */
typedef struct {
    uint8_t cont : 1;   /* 后续状态位 */
    uint8_t res : 5;    /* 预留 */
    uint8_t cr : 1;     /* 取消预置 */
    uint8_t se : 1;     /* 固化/预置 */
} pi_t;

/**
 * @brief TLV数据类型枚举
 */
typedef enum {
    TLV_TYPE_BOOLEAN = 1,           /* 布尔 */
    TLV_TYPE_TINY = 43,             /* 小整形 */
    TLV_TYPE_UTINY = 32,            /* 无符号小整形 */
    TLV_TYPE_SHORT = 33,            /* 短整形 */
    TLV_TYPE_USHORT = 45,           /* 无符号短整形 */
    TLV_TYPE_INT = 2,               /* 整形 */
    TLV_TYPE_UINT = 35,             /* 无符号整形 */
    TLV_TYPE_LONG = 36,             /* 长整形 */
    TLV_TYPE_ULONG = 37,            /* 无符号长整形 */
    TLV_TYPE_FLOAT = 38,            /* 单精度浮点 */
    TLV_TYPE_DOUBLE = 39,           /* 双精度浮点 */
    TLV_TYPE_OCTET_STRING = 4,      /* 八位位串类型 */
    TLV_TYPE_STRING = 8             /* 字符串类型 */
} tlv_data_type_t;

/**
 * @brief TLV数据值联合体
 */
typedef union {
    u8 boolean_value;               /* 布尔值 */
    s8 tiny_value;                 /* 小整形值 */
    u8 utiny_value;                 /* 无符号小整形值 */
    s16 short_value;                /* 短整形值 */
    u16 ushort_value;               /* 无符号短整形值 */
    s32 int_value;                  /* 整形值 */
    u32 uint_value;                 /* 无符号整形值 */
    s64 long_value;                 /* 长整形值 */
    u64 ulong_value;                /* 无符号长整形值 */
    float float_value;               /* 单精度浮点值 */
    double double_value;             /* 双精度浮点值 */
    u8* octet_string_value;          /* 八位位串值 */
    char* string_value;              /* 字符串值 */
} tlv_value_t;

/**
 * @brief TLV数据结构
 */
typedef struct {
    u8 tag;                          /* 标记 */
    u8 length;                       /* 长度 */
    tlv_data_type_t data_type;       /* 数据类型 */
    tlv_value_t value;               /* 数据值 */
    u8* data;                        /* 原始数据 */
} tlv_data_t;

/**
 * @brief 参数数据结构
 */
typedef struct {
    info_addr_t info_address;        /* 信息体地址 */
    u8 setting_area_number;           /* 定值区号 */
    pi_t parameter_identification;   /* 参数特征标识 */
    tlv_data_t tlv_data;             /* TLV数据 */
} parameter_data_t;

/**
 * @brief 参数类型枚举
 */
typedef enum {
    PARAMETER_TYPE_INHERENT = 0,      /* 固有参数 */
    PARAMETER_TYPE_RUNNING = 1,      /* 运行参数 */
    PARAMETER_TYPE_ACTION = 2         /* 动作定值 */
} parameter_type_t;

/**
 * @brief 参数分类枚举
 */
typedef enum {
    PARAMETER_CATEGORY_TERMINAL_TYPE = 0x8001,        /* 终端类型 */
    PARAMETER_CATEGORY_TERMINAL_OS = 0x8002,          /* 终端操作系统 */
    PARAMETER_CATEGORY_TERMINAL_MANUFACTURER = 0x8003, /* 终端制造商 */
    PARAMETER_CATEGORY_TERMINAL_HW_VERSION = 0x8004,  /* 终端硬件版本 */
    PARAMETER_CATEGORY_TERMINAL_SW_VERSION = 0x8005,  /* 终端软件版本 */
    PARAMETER_CATEGORY_TERMINAL_SW_CHECKSUM = 0x8006, /* 终端软件版本校验码 */
    PARAMETER_CATEGORY_TERMINAL_PROTOCOL = 0x8007,    /* 终端通信规约类型 */
    PARAMETER_CATEGORY_TERMINAL_MODEL = 0x8008,       /* 终端出厂型号 */
    PARAMETER_CATEGORY_TERMINAL_ID = 0x8009,          /* 终端ID号 */
    PARAMETER_CATEGORY_TERMINAL_MAC = 0x800A,         /* 终端网卡MAC地址 */
    PARAMETER_CATEGORY_CURRENT_DEAD_ZONE = 0x8020,    /* 电流死区 */
    PARAMETER_CATEGORY_AC_VOLTAGE_DEAD_ZONE = 0x8021, /* 交流电压死区 */
    PARAMETER_CATEGORY_DC_VOLTAGE_DEAD_ZONE = 0x8022, /* 直流电压死区 */
    PARAMETER_CATEGORY_POWER_DEAD_ZONE = 0x8023,      /* 功率死区 */
    PARAMETER_CATEGORY_FREQUENCY_DEAD_ZONE = 0x8024,  /* 频率死区 */
    PARAMETER_CATEGORY_POWER_FACTOR_DEAD_ZONE = 0x8025, /* 功率因数死区 */
    PARAMETER_CATEGORY_PT_PRIMARY_RATING = 0x8026,    /* PT一次额定 */
    PARAMETER_CATEGORY_PT_SECONDARY_RATING = 0x8027, /* PT二次额定 */
    PARAMETER_CATEGORY_LOW_VOLTAGE_ALARM_THRESHOLD = 0x8028, /* 低电压报警门限值 */
    PARAMETER_CATEGORY_LOW_VOLTAGE_ALARM_PERIOD = 0x8029,   /* 低电压报警周期 */
    PARAMETER_CATEGORY_OVER_VOLTAGE_ALARM_THRESHOLD = 0x802A, /* 过电压报警门限值 */
    PARAMETER_CATEGORY_OVER_VOLTAGE_ALARM_PERIOD = 0x802B,   /* 过电压报警周期 */
    PARAMETER_CATEGORY_HEAVY_LOAD_ALARM_THRESHOLD = 0x802C,  /* 重载报警门限值 */
    PARAMETER_CATEGORY_HEAVY_LOAD_ALARM_PERIOD = 0x802D,    /* 重载报警周期 */
    PARAMETER_CATEGORY_OVERLOAD_ALARM_THRESHOLD = 0x802E,   /* 过载报警门限值 */
    PARAMETER_CATEGORY_OVERLOAD_ALARM_PERIOD = 0x802F,       /* 过载报警周期 */
    PARAMETER_CATEGORY_INPUT_DEBOUNCE_TIME = 0x8030,        /* 开入量采集防抖时间 */
    PARAMETER_CATEGORY_OPEN_PULSE_HOLD_TIME = 0x8031,       /* 分闸输出脉冲保持时间 */
    PARAMETER_CATEGORY_CLOSE_PULSE_HOLD_TIME = 0x8032,      /* 合闸输出脉冲保持时间 */
    PARAMETER_CATEGORY_BATTERY_AUTO_ACTIVATION_CYCLE = 0x8033, /* 蓄电池自动活化周期 */
    PARAMETER_CATEGORY_BATTERY_AUTO_ACTIVATION_TIME = 0x8034,  /* 蓄电池自动活化时刻 */
    PARAMETER_CATEGORY_CIRCUIT_CT_PRIMARY_RATING = 0x8040,  /* 回路CT一次额定 */
    PARAMETER_CATEGORY_CIRCUIT_CT_SECONDARY_RATING = 0x8041, /* 回路CT二次额定 */
    PARAMETER_CATEGORY_CIRCUIT_ZERO_CT_PRIMARY_RATING = 0x8042, /* 回路零序CT一次额定 */
    PARAMETER_CATEGORY_CIRCUIT_ZERO_CT_SECONDARY_RATING = 0x8043, /* 回路零序CT二次额定 */
    PARAMETER_CATEGORY_FAULT_LIGHT_AUTO_RESET_ENABLE = 0x8220, /* 故障指示灯自动复归投入 */
    PARAMETER_CATEGORY_FAULT_LIGHT_AUTO_RESET_TIME = 0x8221,   /* 故障指示灯自动复归时间 */
    PARAMETER_CATEGORY_FAULT_TELEMETRY_HOLD_TIME = 0x8222,     /* 故障遥信保持时间 */
    PARAMETER_CATEGORY_FIRST_FTU_ENABLE = 0x8223,             /* 首端FTU投入 */
    PARAMETER_CATEGORY_X_TIME_SETTING = 0x8224,               /* X时间定值 */
    PARAMETER_CATEGORY_Y_TIME_SETTING = 0x8225,               /* Y时间定值 */
    PARAMETER_CATEGORY_C_TIME_SETTING = 0x8226,               /* C时间定值 */
    PARAMETER_CATEGORY_S_TIME_SETTING = 0x8227,               /* S时间定值 */
    PARAMETER_CATEGORY_SINGLE_PHASE_GROUND_TRIP_TIME = 0x8228, /* 单相接地跳闸时间 */
    PARAMETER_CATEGORY_SELECTIVE_TRIP_RECLOSE_TIME = 0x8229, /* 选线跳闸重合时间定值 */
    PARAMETER_CATEGORY_ADAPTIVE_PHASE_FAULT_ENABLE = 0x822A, /* 自适应相间短路故障处理投入 */
    PARAMETER_CATEGORY_ADAPTIVE_GROUND_FAULT_ENABLE = 0x822B, /* 自适应单相接地故障处理投入 */
    PARAMETER_CATEGORY_FIRST_RECLOSE_ENABLE = 0x822C,        /* 一次重合闸投退 */
    PARAMETER_CATEGORY_FIRST_RECLOSE_TIME = 0x822D,          /* 一次重合时间 */
    PARAMETER_CATEGORY_LARGE_CURRENT_BLOCK_RECLOSE_ENABLE = 0x822E, /* 大电流闭锁重投退 */
    PARAMETER_CATEGORY_LARGE_CURRENT_BLOCK_RECLOSE_VALUE = 0x822F,  /* 大电流闭重定值 */
    PARAMETER_CATEGORY_CIRCUIT_OVERLOAD_TRIP_ENABLE = 0x8240, /* 回路过流停电跳闸投退 */
    PARAMETER_CATEGORY_CIRCUIT_OVERLOAD_I_ALARM_ENABLE = 0x8241, /* 回路过流I段告警投退 */
    PARAMETER_CATEGORY_CIRCUIT_OVERLOAD_I_OUTPUT_ENABLE = 0x8242, /* 回路过流I段出口投退 */
    PARAMETER_CATEGORY_CIRCUIT_OVERLOAD_I_VALUE = 0x8243,     /* 回路过流I段定值 */
    PARAMETER_CATEGORY_CIRCUIT_OVERLOAD_I_TIME = 0x8244,     /* 回路过流I段时间 */
    PARAMETER_CATEGORY_CIRCUIT_OVERLOAD_II_ALARM_ENABLE = 0x8245, /* 回路过流II段告警投退 */
    PARAMETER_CATEGORY_CIRCUIT_OVERLOAD_II_OUTPUT_ENABLE = 0x8246, /* 回路过流II段出口投退 */
    PARAMETER_CATEGORY_CIRCUIT_OVERLOAD_II_VALUE = 0x8247,   /* 回路过流II段定值 */
    PARAMETER_CATEGORY_CIRCUIT_OVERLOAD_II_TIME = 0x8248,    /* 回路过流II段时间 */
    PARAMETER_CATEGORY_CIRCUIT_ZERO_OVERLOAD_ALARM_ENABLE = 0x8249, /* 回路零序过流告警投退 */
    PARAMETER_CATEGORY_CIRCUIT_ZERO_OVERLOAD_OUTPUT_ENABLE = 0x824A, /* 回路零序过流出口投退 */
    PARAMETER_CATEGORY_CIRCUIT_ZERO_OVERLOAD_VALUE = 0x824B, /* 回路零序过流定值 */
    PARAMETER_CATEGORY_CIRCUIT_ZERO_OVERLOAD_TIME = 0x824C,  /* 回路零序过流时间 */
    PARAMETER_CATEGORY_CIRCUIT_SMALL_CURRENT_GROUND_ALARM_ENABLE = 0x824D, /* 回路小电流接地告警投退 */
    PARAMETER_CATEGORY_CIRCUIT_SMALL_CURRENT_GROUND_OUTPUT_ENABLE = 0x824E /* 回路小电流接地出口投退 */
} parameter_category_t;

/**
 * @brief 参数数据组
 */
typedef struct {
    parameter_data_t* parameters;     /* 参数数组 */
    u32 count;                        /* 参数个数 */
    u32 max_count;                    /* 最大参数个数 */
} parameter_data_group_t;

/* ==================== 参数特征标识处理函数 ==================== */

/**
 * @brief 参数特征标识转换为字节数组
 * @details 将参数特征标识结构转换为104协议规定的字节数组格式。
 *          按照协议规范进行数据序列化。
 * 
 * @param pi 参数特征标识结构，不能为NULL
 * @param buffer 输出缓冲区，不能为NULL
 * @param buffer_size 缓冲区大小
 * @param actual_length 实际写入长度输出，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 转换成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_BUFFER_TOO_SMALL: 缓冲区太小
 *         - PROTOCOL_ERROR_DATA_INVALID_VALUE: 数据值无效
 * 
 * @note 按照104协议规范进行数据序列化
 * @warning 缓冲区大小必须足够容纳转换后的数据
 * 
 * @see bytes_to_parameter_identification
 * @see validate_parameter_identification
 * @see buffer_write_u8
 */
protocol_error_t parameter_identification_to_bytes(const pi_t* pi,
                                                 u8* buffer, u32 buffer_size, u32* actual_length);

/**
 * @brief 字节数组转换为参数特征标识
 * @details 将104协议规定的字节数组格式转换为参数特征标识结构。
 *          按照协议规范进行数据反序列化。
 * 
 * @param data 字节数组，不能为NULL
 * @param length 数据长度
 * @param pi 参数特征标识结构输出，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 转换成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_BUFFER_TOO_SMALL: 数据长度不足
 *         - PROTOCOL_ERROR_DATA_INVALID_VALUE: 数据值无效
 * 
 * @note 按照104协议规范进行数据反序列化
 * @warning 数据长度必须足够容纳参数特征标识
 * 
 * @see parameter_identification_to_bytes
 * @see validate_parameter_identification
 * @see buffer_read_u8
 */
protocol_error_t bytes_to_parameter_identification(const u8* data, u32 length,
                                                 pi_t* pi);

/**
 * @brief 验证参数特征标识
 * @details 验证参数特征标识结构的完整性和有效性。
 *          检查保留位是否都为0。
 * 
 * @param pi 参数特征标识结构，不能为NULL
 * @return 验证结果
 *         - 1: 参数特征标识有效
 *         - 0: 参数特征标识无效
 * 
 * @note 验证保留位是否都为0
 * @warning 输入指针不能为NULL
 * 
 * @see is_parameter_identification_valid
 * @see pi_t
 */
int validate_parameter_identification(const pi_t* pi);

/* ==================== TLV数据处理函数 ==================== */

/**
 * @brief TLV数据转换为字节数组
 * @details 将TLV数据结构转换为104协议规定的字节数组格式。
 *          按照协议规范进行数据序列化。
 * 
 * @param tlv TLV数据结构，不能为NULL
 * @param buffer 输出缓冲区，不能为NULL
 * @param buffer_size 缓冲区大小
 * @param actual_length 实际写入长度输出，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 转换成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_BUFFER_TOO_SMALL: 缓冲区太小
 *         - PROTOCOL_ERROR_DATA_INVALID_VALUE: 数据值无效
 * 
 * @note 按照104协议规范进行数据序列化
 * @warning 缓冲区大小必须足够容纳转换后的数据
 * 
 * @see bytes_to_tlv_data
 * @see validate_tlv_data
 * @see buffer_write_u8
 * @see buffer_write_u16
 * @see buffer_write_string
 */
protocol_error_t tlv_data_to_bytes(const tlv_data_t* tlv,
                                 u8* buffer, u32 buffer_size, u32* actual_length);

/**
 * @brief 字节数组转换为TLV数据
 * @details 将104协议规定的字节数组格式转换为TLV数据结构。
 *          按照协议规范进行数据反序列化。
 * 
 * @param data 字节数组，不能为NULL
 * @param length 数据长度
 * @param tlv TLV数据结构输出，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 转换成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_BUFFER_TOO_SMALL: 数据长度不足
 *         - PROTOCOL_ERROR_DATA_INVALID_VALUE: 数据值无效
 *         - PROTOCOL_ERROR_MEMORY_ALLOCATION: 内存分配失败
 * 
 * @note 按照104协议规范进行数据反序列化
 * @warning 数据长度必须足够容纳TLV数据
 * 
 * @see tlv_data_to_bytes
 * @see validate_tlv_data
 * @see buffer_read_u8
 * @see buffer_read_u16
 */
protocol_error_t bytes_to_tlv_data(const u8* data, u32 length,
                                 tlv_data_t* tlv);

/**
 * @brief 验证TLV数据
 * @details 验证TLV数据结构的完整性和有效性。
 *          检查类型、长度和数据的有效性。
 * 
 * @param tlv TLV数据结构，不能为NULL
 * @return 验证结果
 *         - 1: TLV数据有效
 *         - 0: TLV数据无效
 * 
 * @note 验证类型、长度和数据的有效性
 * @warning 输入指针不能为NULL
 * 
 * @see is_tlv_data_type_valid
 * @see is_tlv_data_length_valid
 * @see tlv_data_t
 */
int validate_tlv_data(const tlv_data_t* tlv);

/* ==================== 参数读写命令处理函数 ==================== */

/**
 * @brief 参数读写命令转换为字节数组
 * @details 将参数读写命令结构转换为104协议规定的字节数组格式。
 *          按照协议规范进行数据序列化。
 * 
 * @param command 参数读写命令结构，不能为NULL
 * @param buffer 输出缓冲区，不能为NULL
 * @param buffer_size 缓冲区大小
 * @param actual_length 实际写入长度输出，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 转换成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_BUFFER_TOO_SMALL: 缓冲区太小
 *         - PROTOCOL_ERROR_DATA_INVALID_VALUE: 数据值无效
 * 
 * @note 按照104协议规范进行数据序列化
 * @warning 缓冲区大小必须足够容纳转换后的数据
 * 
 * @see bytes_to_parameter_command
 * @see validate_parameter_command
 * @see buffer_write_u24
 * @see buffer_write_u8
 * @see tlv_data_to_bytes
 */
protocol_error_t parameter_command_to_bytes(const parameter_data_t* command,
                                           u8* buffer, u32 buffer_size, u32* actual_length);

/**
 * @brief 字节数组转换为参数读写命令
 * @details 将104协议规定的字节数组格式转换为参数读写命令结构。
 *          按照协议规范进行数据反序列化。
 * 
 * @param data 字节数组，不能为NULL
 * @param length 数据长度
 * @param command 参数读写命令结构输出，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 转换成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_BUFFER_TOO_SMALL: 数据长度不足
 *         - PROTOCOL_ERROR_ASDU_INVALID_ADDRESS: 地址无效
 *         - PROTOCOL_ERROR_DATA_INVALID_VALUE: 数据值无效
 * 
 * @note 按照104协议规范进行数据反序列化
 * @warning 数据长度必须足够容纳参数读写命令
 * 
 * @see parameter_command_to_bytes
 * @see validate_parameter_command
 * @see buffer_read_u24
 * @see buffer_read_u8
 * @see bytes_to_tlv_data
 */
protocol_error_t bytes_to_parameter_command(const u8* data, u32 length,
                                            parameter_data_t* command);

/**
 * @brief 验证参数读写命令
 * @details 验证参数读写命令结构的完整性和有效性。
 *          检查地址、参数特征标识和TLV数据的有效性。
 * 
 * @param command 参数读写命令结构，不能为NULL
 * @return 验证结果
 *         - 1: 参数读写命令有效
 *         - 0: 参数读写命令无效
 * 
 * @note 验证地址、参数特征标识和TLV数据的有效性
 * @warning 输入指针不能为NULL
 * 
 * @see is_info_address_valid
 * @see is_parameter_identification_valid
 * @see validate_tlv_data
 * @see parameter_command_t
 */
int validate_parameter_command(const parameter_data_t* command);

/* ==================== 辅助函数 ==================== */

/**
 * @brief 获取参数特征标识大小
 * @details 获取参数特征标识结构在字节数组中的大小。
 *          用于缓冲区大小计算。
 * 
 * @return 参数特征标识大小（字节）
 * 
 * @note 参数特征标识大小：1字节
 * @warning 此函数是线程安全的
 * 
 * @see get_tlv_data_size
 * @see get_parameter_command_size
 * @see pi_t
 */
u32 get_parameter_identification_size(void);

/**
 * @brief 获取TLV数据大小
 * @details 获取TLV数据结构在字节数组中的大小。
 *          用于缓冲区大小计算。
 * 
 * @param tlv TLV数据结构，不能为NULL
 * @return TLV数据大小（字节）
 * 
 * @note TLV数据大小：1字节 + 2字节 + 数据长度
 * @warning 输入指针不能为NULL
 * 
 * @see get_parameter_identification_size
 * @see get_parameter_command_size
 * @see tlv_data_t
 */
u32 get_tlv_data_size(const tlv_data_t* tlv);

/**
 * @brief 获取参数读写命令大小
 * @details 获取参数读写命令结构在字节数组中的大小。
 *          用于缓冲区大小计算。
 * 
 * @param command 参数读写命令结构，不能为NULL
 * @return 参数读写命令大小（字节）
 * 
 * @note 参数读写命令大小：地址(3字节) + PI(1字节) + TLV数据大小
 * @warning 输入指针不能为NULL
 * 
 * @see get_parameter_identification_size
 * @see get_tlv_data_size
 * @see parameter_command_t
 */
u32 get_parameter_command_size(const parameter_data_t* command);

/* ==================== TLV数据类型处理函数 ==================== */

/**
 * @brief 获取TLV数据类型名称
 * @details 根据TLV数据类型枚举值获取对应的中文名称。
 *          用于调试和日志输出。
 * 
 * @param type TLV数据类型枚举值
 * @return TLV数据类型名称字符串
 * 
 * @note 返回的字符串是静态的，不需要释放
 * @warning 无效类型返回"未知类型"
 * 
 * @see tlv_data_type_t
 * @see get_tlv_data_type_description
 */
const char* get_tlv_data_type_name(tlv_data_type_t type);

/**
 * @brief 获取TLV数据类型描述
 * @details 根据TLV数据类型枚举值获取对应的详细描述。
 *          用于调试和日志输出。
 * 
 * @param type TLV数据类型枚举值
 * @return TLV数据类型描述字符串
 * 
 * @note 返回的字符串是静态的，不需要释放
 * @warning 无效类型返回"未知类型"
 * 
 * @see tlv_data_type_t
 * @see get_tlv_data_type_name
 */
const char* get_tlv_data_type_description(tlv_data_type_t type);

/* ==================== TLV数据操作函数 ==================== */

/**
 * @brief 销毁TLV数据
 * @details 销毁TLV数据结构，释放内存。
 *          用于清理TLV数据。
 * 
 * @param tlv TLV数据结构，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 销毁成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 * 
 * @note 销毁TLV数据结构，释放内存
 * @warning 输入指针不能为NULL
 * 
 * @see create_tlv_data
 * @see copy_tlv_data
 * @see tlv_data_t
 */
protocol_error_t destroy_tlv_data(tlv_data_t* tlv);

/**
 * @brief 复制TLV数据
 * @details 复制TLV数据结构，分配内存并复制数据。
 *          用于复制TLV数据。
 * 
 * @param src 源TLV数据结构，不能为NULL
 * @param dst 目标TLV数据结构，不能为NULL
 * @return 协议错误码
 *         - PROTOCOL_SUCCESS: 复制成功
 *         - PROTOCOL_ERROR_NULL_POINTER: 空指针错误
 *         - PROTOCOL_ERROR_MEMORY_ALLOCATION: 内存分配失败
 * 
 * @note 复制TLV数据结构，分配内存并复制数据
 * @warning 输入指针不能为NULL
 * 
 * @see create_tlv_data
 * @see destroy_tlv_data
 * @see tlv_data_t
 */
protocol_error_t copy_tlv_data(const tlv_data_t* src, tlv_data_t* dst);

/* ==================== 验证辅助函数 ==================== */

/**
 * @brief 验证参数特征标识
 * @details 验证参数特征标识是否在有效范围内。
 *          检查保留位是否都为0。
 * 
 * @param pi 参数特征标识
 * @return 验证结果
 *         - 1: 参数特征标识有效
 *         - 0: 参数特征标识无效
 * 
 * @note 参数特征标识只有3位有效，其他位必须为0
 * @warning 保留位必须为0
 * 
 * @see is_tlv_data_type_valid
 * @see is_tlv_data_length_valid
 * @see pi_t
 */
int is_parameter_identification_valid(const pi_t* pi);

/**
 * @brief 验证TLV数据类型
 * @details 验证TLV数据类型是否在有效范围内。
 *          TLV数据类型范围：1-45
 * 
 * @param type TLV数据类型
 * @return 验证结果
 *         - 1: TLV数据类型有效
 *         - 0: TLV数据类型无效
 * 
 * @note TLV数据类型范围：1-45
 * @warning TLV数据类型不能为0
 * 
 * @see is_parameter_identification_valid
 * @see is_tlv_data_length_valid
 * @see tlv_data_type_t
 */
int is_tlv_data_type_valid(tlv_data_type_t type);

/**
 * @brief 验证TLV数据长度
 * @details 验证TLV数据长度是否在有效范围内。
 *          TLV数据长度范围：0-65535
 * 
 * @param length TLV数据长度
 * @return 验证结果
 *         - 1: TLV数据长度有效
 *         - 0: TLV数据长度无效
 * 
 * @note TLV数据长度范围：0-65535
 * @warning TLV数据长度不能为负数
 * 
 * @see is_tlv_data_type_valid
 * @see is_parameter_identification_valid
 */
int is_tlv_data_length_valid(u16 length);

/**
 * @brief 验证TLV数据
 * @details 验证TLV数据结构的完整性和有效性。
 *          检查类型、长度和数据的有效性。
 * 
 * @param tlv TLV数据结构，不能为NULL
 * @return 验证结果
 *         - 1: TLV数据有效
 *         - 0: TLV数据无效
 * 
 * @note 验证类型、长度和数据的有效性
 * @warning 输入指针不能为NULL
 * 
 * @see is_tlv_data_type_valid
 * @see is_tlv_data_length_valid
 * @see tlv_data_t
 */
int is_tlv_data_valid(const tlv_data_t* tlv);

/**
 * @brief 验证参数读写命令
 * @details 验证参数读写命令是否在有效范围内。
 *          检查地址、参数特征标识和TLV数据的有效性。
 * 
 * @param command 参数读写命令结构，不能为NULL
 * @return 验证结果
 *         - 1: 参数读写命令有效
 *         - 0: 参数读写命令无效
 * 
 * @note 验证地址、参数特征标识和TLV数据的有效性
 * @warning 输入指针不能为NULL
 * 
 * @see is_info_address_valid
 * @see is_parameter_identification_valid
 * @see validate_tlv_data
 * @see parameter_command_t
 */
int is_parameter_command_valid(const parameter_data_t* command);

#ifdef __cplusplus
}
#endif

#endif /* PARAMETER_DATA_H */
